Release notes

2024r2

Additional attributes and drop-down call in curation API

In a previous version, the curation API was introduced, which allows to retrieve, create, and update product pages and product page snapshots (RN-6072).

In this version, the following attributes have been added to the response of the GET /productPages/{productPageId} call:

  • publicationStatus:
    This returns the API reference of the value of the Publication status field of the product page. (RN-6115)

  • dateCreatedUTC:
    This returns the timestamp of the date and time on which the product page was created in the UTC timezone. It corresponds to the Created on field on the product page.

  • dateModifiedUTC:
    This returns the timestamp of the date and time on which the product page was last modified in the UTC timezone. It corresponds to the Changed on field on the product page.

An example of the response body of the call:

{
    "productPageId": "9500438855",
    "name": "AVENGERS: ENDGAME",
    "displayTitle": "Avengers: Endgame",
    "translatedDisplayTitle": "อเวนเจอร์ส: เผด็จศึกz",
     ...
    "publicationStatus": "newInputAfterPublication",
    "dateCreatedUTC": "2023-12-28T10:06:15.514+00:00",
    "dateModifiedUTC": "2024-01-19T14:09:17.016+00:00"
}

Additionally, a GET /externalSystemResponses call has been added to retrieve the drop-down values of the PLExternalSystemResponse drop-down list. The id of the values can then be used in the PUT /productPageSnapshots/{productPageSnapshotId} call.

An example of the response:

[
    {
        "id": "Received",
        "name": "Received"
    },
    {
        "id": "Error",
        "name": "Error"
    }
]

The YAML has been updated for these changes. The latest version can be retrieved by using the GET /api call.

2023r13

Addition of Curation API

In the previous version, the nodes and navigation nodes were reworked to become product pages and curation nodes. (RN-6072)

Product pages determine how content will be presented on an on-demand platform, so they also need to be exported to external systems. Sometimes, the product page on a platform is even available before the actual content, for example, to announce when it is coming.

Exporting product pages can be done by publishing the product page structure, which creates a product page snapshot.

From this version, the curation API has been introduced, which allows to retrieve, create, and update product pages and product page snapshots.

When opening or creating a Business API interface service, the Curation API can be added to the BUSINESS API DEFINITIONS list if it has been made available in the WONComponent drop-down list.

The YAML file can be retrieved by executing the /api call. The latest version can also be found on the API Explorer.

The curation API contains calls for managing

  • product pages;

  • product page snapshots.

Product pages

From this version, the curation API has been introduced, which allows to retrieve, create, and update product pages and product page snapshots.

It contains the following calls for product pages.

PUT and POST /productPages

The POST call can be used to create product pages, and the PUT and POST can be used to update them by providing the external reference in the URL of the call. With these calls, the editable properties of the product page can be defined or it can be marked as landing page (RN-6114). It is not possible to add or delete subpages or link or remove transmissions.

Note that when you are creating a product page using the POST call, the name and parentProductPage attributes should be part of the call. The latter determines under which product page the new one will be created. If it not included, it will be created as a page on the highest level. In the PUT call, it will be ignored as the order of existing pages can only changed by using the Reorder product pages... command (RN-6110).

An example of the body:

{
    "productPageId": "9500438855",
    "name": "BARBIE",
    "displayTitle": "Barbie",
    "translatedDisplayTitle": "ตุ๊กตาบาร์บี้",
    "type": "Product page",
    "isLandingPage": false,
    "description": "Barbie and Ken are having the time of their lives in the colorful and seemingly perfect world of Barbie Land.
                    However, when they get a chance to go to the real world, they soon discover the joys and perils of living among humans.",
    "translatedDescription1": null,
    "translatedDescription2": null,
    "parentProductPage": "9500443903"
}

The type attribute maps to the PLProductPageType drop-down list. The available values can be retrieved using the GET /types drop-down call.

An example of the response:

    {
        "id": "Product page",
        "name": "Product page"
    },
    {
        "id": "Series overview",
        "name": "Series overview"
    }

GET /productPages/{productPageId}

This call can be used to retrieve the details of a single product page by providing the external reference in the URL of the call.

An example of the response:

{
    "productPageId": "9500438855",
    "name": "AVENGERS: ENDGAME",
    "displayTitle": "Avengers: Endgame",
    "translatedDisplayTitle": "อเวนเจอร์ส: เผด็จศึก",
    "type": "Product page",
    "isLandingPage": false,
    "description": "The Avengers try to save half the universe after the Blip.",
    "translatedDescription1": "อเวนเจอร์สพยายามกอบกู้ครึ่งจักรวาลหลังจากเหตุการณ์ Blip",
    "translatedDescription2": null,
    "parentProductPage": "9500443903",
    "sequenceNo": 2,
    "kind": "subPage",
    "parentalRating": "12",
    "lastPublishedOn": "2024-01-05T14:53:34Z",
    "numberOfSubPages": 2,
    "subPages": [
        "9500443997",
        "9500443995"
    ],
    "linkedTransmissions": [
        "2588669812",
        "9248910812",
        "9500432307"
    ]
}

The parentalRating attribute maps to the WOnProgramCertification drop-down list. The available values can be retrieved using the GET /parentalRatings drop-down call.

GET /productPages

This call can be used to search for product pages. It is possible to search using the name attribute as filter and sort parameters.

An example of the URL: GET /productPages?filter=eq(name,Bonus)

It returns a list of the pages that match the parameter and gives a limited number of properties.

An example of the response:

    {
        "productPageId": "9500443993",
        "name": "Bonus",
        "kind": "subPage"
    },
    {
        "productPageId": "9500443995",
        "name": "Bonus",
        "kind": "subPage"
    }

DELETE /productPages/{productPageId}

This call is used to delete a specific product page defined by its external reference.

If the product page has transmissions linked, a 403 error is returned:

{
    "statusCode": "403",
    "message": "Forbidden",
    "timestamp": "2024-01-19T15:06:42Z",
    "concept": "Product page",
    "id": "9500491091",
    "errors": [
        {
            "errorCode": "CURATION-00002",
            "description": "The product page or his children have transmissions linked to it. Please remove all the existing transmission links before deleting the node.",
            "data": []
        }
    ]
}

See the API Explorer for more information on the attributes.

Product page snapshots

From this version, the curation API has been introduced, which allows to retrieve, create, and update product pages and product page snapshots.

It contains the following calls for product page snapshots.

PUT /productPageSnapshots/{productPageSnapshotId}

This call will allow the downstream publication system to update the product page snapshot with some feedback around the status of the publication or activation of the product page on the on-demand platform. The call contains two attributes that can be used to update this feedback on the snapshot:

  • externalSystemResponse:
    This maps to the External system response field on a product page snapshot, which takes its values from the PLExternalSystemResponse drop-down list. (RN-6115) This attribute should contain the API reference of the drop-down value.

  • externalSystemRemarks:
    This maps to the External system remarks field on a product page snapshot and just contains text. (RN-6115)

An example of the body:

{
  "productPageSnapshotId": 923849240,
  "externalSystemResponse": "Activated",
  "externalSystemRemarks": "Failed due to violations: missing metadata"
}

GET /productPageSnapshots

This call can be used to search for product page snapshots. It is possible to search using the publishedOn and productPageId attributes as filter parameters.

An example of the URL: GET /productPageSnapshots?filter=gt(publishedOn,2023-10-01 10:10:10.000)

It returns a list of the snapshots that match the parameter and gives a limited number of properties. By default, the last created snapshots will be at the top of the list.

An example of the response:

[
  {
    "name": "meWatch",
    "productPageSnapshotId": 183501002,
    "kind": "rootPage",
    "productPageId": 9232343,
    "publishedOn": "2023-10-25T12:26:04.174Z"
  }
]

GET /productPages/{productPageId}

This call can be used to retrieve the details of a single product page snapshot by providing the external reference in the URL of the call. This gives the external system information on what a product page structure looks like.

For example, you have the following product page structure in WHATS'ON:

  • Movies

    • Avengers: Endgame

      • Bonus

This is an example of the response for that structure:

{
    "productPageSnapshotId": "9500490810",
    "productPageId": "9500443903",
    "name": "Movies",
    "displayTitle": "Movies",
    "translatedDisplayTitle": "Films",
    "type": null,
    "isLandingPage": true,
    "description": "All films available on our platform",
    "translatedDescription1": null,
    "translatedDescription2": null,
    "sequenceNo": 1,
    "kind": "rootPage",
    "parentalRating": null,
    "numberOfSubPages": 1,
    "subPageSnapshots": [
        {
            "productPageSnapshotId": "9500490812",
            "productPageId": "9500438855",
            "name": "AVENGERS: ENDGAME",
            "displayTitle": "Avengers: Endgame",
            "translatedDisplayTitle": "อเวนเจอร์ส: เผด็จศึก",
            "type": "Product page",
            "isLandingPage": false,
            "description": "The Avengers try to save half the universe after the Blip.",
            "translatedDescription1": "อเวนเจอร์สพยายามกอบกู้ครึ่งจักรวาลหลังจากเหตุการณ์ Blip",
            "translatedDescription2": null,
            "sequenceNo": 1,
            "kind": "subPage",
            "parentalRating": "12",
            "numberOfSubPages": 2,
            "subPageSnapshots": [
                {
                    "productPageSnapshotId": "9500490814",
                    "productPageId": "9500443995",
                    "name": "Bonus",
                    "displayTitle": null,
                    "translatedDisplayTitle": null,
                    "type": null,
                    "isLandingPage": false,
                    "description": null,
                    "translatedDescription1": null,
                    "translatedDescription2": null,
                    "sequenceNo": 1,
                    "kind": "subPage",
                    "parentalRating": null,
                    "numberOfSubPages": 0,
                    "subPageSnapshots": [],
                    "publishedOn": "2024-01-19T13:34:37Z",
                    "versionNumber": 4,
                    "externalSystemResponse": null,
                    "externalSystemRemarks": null
                }
            ],
            "publishedOn": "2024-01-19T13:34:37Z",
            "versionNumber": 4,
            "externalSystemResponse": null,
            "externalSystemRemarks": null
        }
    ],
    "publishedOn": "2024-01-19T13:34:37Z",
    "versionNumber": 4,
    "externalSystemResponse": null,
    "externalSystemRemarks": null
}

See the API Explorer for more information on the attributes.